EventAvail

EventAvail
Header:	Events.h		Carbon status:	Supported

Retrieves the next available event from the Event Manager without removing the returned event from your application’s event stream.

Boolean EventAvail (
    EventMask eventMask, 
    EventRecord *theEvent
);

eventMask: A value that indicates which kinds of events are to be returned; this parameter is interpreted as a sum of event mask constants. You specify the event mask using one or more of the values defined by the “EventMask Constant”. If no event of any of the designated types is available, EventAvail returns a null event.
theEvent: A pointer to an event structure for the next available event of the specified type or types. The EventAvail function does not remove the returned event from the event stream, but does return the information about the event in an event structure. The event structure includes the type of event received and other information.

function result: EventAvail returns false as its function result if the event being returned is a null event; otherwise, EventAvail returns true.

DISCUSSION

Like WaitNextEvent, the EventAvail function calls SystemTask to give time to each open desk accessory or device driver to perform any periodic action defined for it. The EventAvail function also makes the alarm go off if the alarm is set and the current time is the alarm time. The user sets the alarm using the Alarm Clock desk accessory.

SPECIAL CONSIDERATIONS

If EventAvail returns a low-level event from the Operating System event queue, the event will not be accessible later if, in the meantime, the event queue becomes full and the event is discarded from it; however, this is not a common occurrence.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.